A quantity is a value type - #210

Every generated physical quantity was a record class deriving from an abstract PhysicalQuantity, whose Create was:

new TQuantity() with { Quantity = value }

That is two heap allocations for one number — new TQuantity() builds an instance and with clones it — and every operator and every unit factory went through it.

Measured

Length<double>, allocation per operation, before and after:

In a loop over a few thousand entities at 60 Hz that is tens of megabytes a second of garbage, from the library whose entire job is to be the type a number is stored in. QuantityValueTypeTests measures it now, so it cannot come back quietly.

What changed

All 212 generated quantities are readonly record struct. A struct cannot inherit, so the abstract PhysicalQuantity record is gone and what it carried is split in two:

• IPhysicalQuantity<TSelf, T> declares static abstract TSelf Create(T), replacing the where TSelf : PhysicalQuantity<TSelf, T>, new() constraint the CRTP base needed, so generic code over quantities still works.
• PhysicalQuantityCore holds the validity and cross-dimension comparison rules. Each quantity delegates in one line rather than carrying a copy, and the receiver is taken by in so delegating does not box it.

Arithmetic, ordering and the IPhysicalQuantity surface are emitted per type. That is not merely how the surface is kept — it is the point: an operator declared on the struct is a plain expression the JIT inlines, where the shared generic base allocated a result object every time. The cross-dimensional operators, which called the inherited Multiply/Divide helpers, construct their result directly for the same reason.

SemanticQuantity<TStorage> and SemanticQuantity<TSelf, TStorage> are untouched. They remain available for a reference-type semantic quantity; the physical quantities simply no longer derive from them.

Behaviour preserved

The Vector0 non-negativity guards, the strictly-positive guards, divide-by-zero, V0's T.Abs(left - right) subtraction, implicit widening to a semantic overload's base, In(unit), Dimension, ToString as the bare value, and CompareTo/Equals throwing and not-throwing respectively across dimensions.

The 1119 existing tests pass unchanged, which is the evidence for that claim. Six new tests cover the value-type and allocation properties.

The one behaviour given up

A struct always has a zero value that no factory intercepts. For every quantity whose invariant is non-negativity that is fine, since zero satisfies it. For the three declaring physicalConstraints.minExclusive: "0" — Wavelength, Period, HalfLife — default reaches a value From{Unit}(0) refuses. A test pins that rather than leaving it to be discovered, and docs/migration-guide-4.0.md says so plainly.

Verification

• dotnet build -c Release — 0 warnings, 0 errors across net8.0 / net9.0 / net10.0
• 1125 tests pass (1119 baseline + 6 new), 0 failures
• SonarCloud analyzers run locally per CLAUDE.md — no findings in changed code (5 pre-existing findings remain in DirectoryNameTests.cs and TextValidationAttributesTests.cs, untouched here)
• Alias props are keyed off generated filenames, which are unchanged, so verify-generated should be clean

Docs

docs/migration-guide-4.0.md is new. CLAUDE.md, docs/architecture.md, docs/physics-generator.md and docs/strategy-unified-vector-quantities.md are updated to match.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AhoPJ5AbxP8QEBNxPQYEPk

Generated by Claude Code